docs/development/Building in Windows 10 or 11 with Linux Subsystem.md

   1 # Building in Windows 10 with Linux subsystem [Recommended]
   2
   3 Linux subsystem for Windows 10 is probably the simplest way of building INAV under Windows 10.
   4
   5 ## Setting up the environment
   6
   7 Enable WSL:
   8 run `windows features`
   9 enable `windows subsytem for linux`
  10 reboot
  11
  12
  13 Install Ubuntu:
  14 1.  Go to Microsoft store https://www.microsoft.com/en-gb/store/b/home
  15 1.  Search and install most recent Ubuntu LTS version
  16 1.  When download completed, select `Launch Ubuntu`
  17 1.  When prompted enter a user name and password which you will need to remember
  18 1.  When complete, the linux command prompt will be displayed
  19
  20 NOTE: from this point all commands are entered into the Ubunto shell command window
  21
  22 Update the repo packages:
  23 -  `sudo apt update`
  24
  25 Install Git, Make, gcc and Ruby
  26 -  `sudo apt-get install git make cmake ruby`
  27
  28 Install python and python-yaml to allow updates to settings.md
  29 -  `sudo apt-get install python3 python-yaml`
  30
  31 ### CMAKE and Ubuntu 18_04
  32
  33 To run  `cmake` in the latest version you will need to update from Ubuntu `18_04` to `20_04`. The fastest way to do it is to uninstall current version and install `20_04` for Microsoft Store [https://www.microsoft.com/store/productId/9N6SVWS3RX71](https://www.microsoft.com/store/productId/9N6SVWS3RX71)
  34
  35 ## Downloading the INAV repository (example):
  36
  37 Mount MS windows C drive and clone INAV
  38 1.   `cd /mnt/c`
  39 1.   `git clone https://github.com/iNavFlight/inav.git`
  40
  41 You are ready!
  42 You now have a folder called inav in the root of C drive that you can edit in windows
  43
  44 ### If you get a cloning error
  45
  46 On some installations, you may see the following error:
  47 ```
  48 Cloning into 'inav'...
  49 error: chmod on /mnt/c/inav/.git/config.lock failed: Operation not permitted
  50 fatal: could not set 'core.filemode' to 'false'
  51 ```
  52
  53 You can fix this with by remounting the drive using the following commands
  54 1. `sudo umount /mnt/c`
  55 2. `sudo mount -t drvfs C: /mnt/c -o metadata`
  56
  57 ## Building (example):
  58
  59 For detailed build instrusctions see [Building in Linux](Building%20in%20Linux.md)
  60
  61 Launch Ubuntu:
  62 Click Windows Start button then scroll and lauch "Ubuntu"
  63
  64 Building from Ubuntu command line
  65
  66 `cd /mnt/c/inav`
  67
  68 Do it onece to prepare build environment
  69 ```
  70 mkdir build
  71 cd build
  72 cmake ..
  73 ```
  74
  75 Then to build
  76 ```
  77 cd build
  78 make MATEKF722
  79 ```
  80
  81 ## Updating the documents
  82 ```
  83 cd /mnt/c/inav
  84 python3 src/utils/update_cli_docs.py
  85 ```
  86
  87 ## Flashing:
  88 Launch windows configurator GUI and from within the firmware flasher select `Load firmware[Local]`
  89 Hex files can be found in the folder `c:\inav\build`
  90
  91 ## Troubleshooting
  92
  93 ### Syntax error: "(" unexpected
  94
  95 ```
  96 dzikuvx@BerlinAtHome:/mnt/c/Users/pspyc/Documents/Projects/inav/build$ make MATEKF722SE
  97 Generating MATEKF722SE/settings_generated.h, MATEKF722SE/settings_generated.c
  98 /bin/sh: 1: Syntax error: "(" unexpected
  99 make[3]: *** [src/main/target/MATEKF722SE/CMakeFiles/MATEKF722SE.elf.dir/build.make:63: src/main/target/MATEKF722SE/MATEKF722SE/settings_generated.h] Error 2
 100 make[2]: *** [CMakeFiles/Makefile2:33607: src/main/target/MATEKF722SE/CMakeFiles/MATEKF722SE.elf.dir/all] Error 2
 101 make[1]: *** [CMakeFiles/Makefile2:33290: src/main/target/MATEKF722SE/CMakeFiles/MATEKF722SE.dir/rule] Error 2
 102 make: *** [Makefile:13703: MATEKF722SE] Error 2
 103 ```
 104
 105 This error can be triggered by a Windows PATHs included in the Linux Subsystem. The solution is:
 106
 107 #### For WSL V1 - Flags set as 7 by default
 108
 109 1. Open Windows RegEdit tool
 110 1. Find `HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Lxss\{GUID}\Flags`
 111 1. Change `Flags` from `7` to `5`
 112 1. Restart WSL and Windows preferably
 113 1. `cd build`
 114 1. `cmake ..`
 115 1. `make {TARGET}` should be working again
 116
 117 #### For WSL V2 - Flags set as 0x0000000f (15) by default
 118 1. Open Windows RegEdit tool
 119 1. Find `HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Lxss\{GUID}\Flags`
 120 1. Change `Flags` from `f` to `d`, it is stored as Base Hexadecimal
 121 1. Restart WSL and Windows preferably
 122 1. `cd build`
 123 1. `cmake ..`
 124 1. `make {TARGET}` should be working again
 125
 126 #### Or, for either version
 127 1. In the Linux Subsystem, `cd /etc/`
 128 2. Create a new file with `sudo nano wsl.conf`
 129 3. Enter the following in to the new file:
 130 ```
 131 [Interop]
 132 appendWindowsPath=false
 133 ```
 134 4. Save the file by holding `Ctrl` and pressing `o`
 135 5. Press `Enter` to confirm the wsl.conf filename.
 136 6. Hit `Ctrl`+`x` to exit nano
 137 7. Restart WSL and Windows preferably
 138 8. `cd build`
 139 9. `cmake ..`
 140 9. `make {TARGET}` should be working again
 141
 142 ### Building targets is very slow
 143 I was pretty shocked when my new i7 -10750 laptop took 25 minutes to build a single target. My old i3-4030 could do the same job in about 2.5 minutes. If you're also suffering from slow builds. Open an elevated PowerShell window and type
 144 ```
 145 wsl -l -v
 146 ```
 147 If you see your Linux distribution is using WSL 2, this is the problem. WSL 2 is quicker than WSL 1 for a lot of things. However, if your files are on a windows mounted drive in Linux, it is extremely slow. There are two options:
 148 1. Put your files on the Linux file system
 149 2. Change to WSL 1
 150
 151 #### Using the Linux file system (recommended)
 152 To use the Linux file system, make sure the distro is running. Open File Explorer and navigate to `\\wsl$`. In that path you will find your distros listed. At this point, map a network drive to your distro. Inside the distro, you can find your home directory at `/home/~username~/`. Create your GitHub folders here.
 153
 154 If after this you have problems with writing to the directories from within VSCode. Open the application for your distro and type
 155 ```
 156 sudo chown -R ~username~ GitHub
 157 ```
 158 `~Username~` is your root distro user that you created and `GitHub` should be the root folder for your GitHub repositories.
 159
 160 #### To switch back to WSL 1
 161 To do this, in the elevated PowerShell window, you can see the name of your distro. Mine is **Ubuntu-20.04**, so I'll use that in this example. Simply type
 162 ```
 163 wsl --set-version Ubuntu-20.04 1
 164 ```
 165 and your distro will be converted to WSL 1. Once finished, reboot your system. Next time you compile a build, it will be faster.